home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / Image.java < prev    next >
Text File  |  1998-09-22  |  8KB  |  197 lines
  1. /*
  2.  * @(#)Image.java    1.24 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14. package java.awt;
  15.  
  16. import java.awt.image.ImageProducer;
  17. import java.awt.image.ImageObserver;
  18. import java.awt.image.ImageFilter;
  19. import java.awt.image.FilteredImageSource;
  20. import java.awt.image.AreaAveragingScaleFilter;
  21. import java.awt.image.ReplicateScaleFilter;
  22.  
  23. /**
  24.  * The abstract class <code>Image</code> is the superclass of all 
  25.  * classes that represent graphical images. The image must be 
  26.  * obtained in a platform-specific manner.
  27.  *
  28.  * @version     1.24, 07/01/98
  29.  * @author     Sami Shaio
  30.  * @author     Arthur van Hoff
  31.  * @since       JDK1.0
  32.  */
  33. public abstract class Image {
  34.     /**
  35.      * Determines the width of the image. If the width is not yet known, 
  36.      * this method returns <code>-1</code> and the specified   
  37.      * <code>ImageObserver</code> object is notified later.
  38.      * @param     observer   an object waiting for the image to be loaded.
  39.      * @return    the width of this image, or <code>-1</code> 
  40.      *                   if the width is not yet known.
  41.      * @see       java.awt.Image#getHeight
  42.      * @see       java.awt.image.ImageObserver
  43.      * @since     JDK1.0
  44.      */
  45.     public abstract int getWidth(ImageObserver observer);
  46.  
  47.     /**
  48.      * Determines the height of the image. If the height is not yet known, 
  49.      * this method returns <code>-1</code> and the specified  
  50.      * <code>ImageObserver</code> object is notified later.
  51.      * @param     observer   an object waiting for the image to be loaded.
  52.      * @return    the height of this image, or <code>-1</code> 
  53.      *                   if the height is not yet known.
  54.      * @see       java.awt.Image#getWidth
  55.      * @see       java.awt.image.ImageObserver
  56.      * @since     JDK1.0
  57.      */
  58.     public abstract int getHeight(ImageObserver observer);
  59.  
  60.     /**
  61.      * Gets the object that produces the pixels for the image.
  62.      * This method is called by the image filtering classes and by 
  63.      * methods that perform image conversion and scaling.
  64.      * @return     the image producer that produces the pixels 
  65.      *                                  for this image.
  66.      * @see        java.awt.image.ImageProducer
  67.      */
  68.     public abstract ImageProducer getSource();
  69.  
  70.     /**
  71.      * Creates a graphics context for drawing to an off-screen image. 
  72.      * This method can only be called for off-screen images. 
  73.      * @return  a graphics context to draw to the off-screen image. 
  74.      * @see     java.awt.Graphics
  75.      * @see     java.awt.Component#createImage(int, int)
  76.      * @since   JDK1.0
  77.      */
  78.     public abstract Graphics getGraphics();
  79.  
  80.     /**
  81.      * Gets a property of this image by name. 
  82.      * <p>
  83.      * Individual property names are defined by the various image 
  84.      * formats. If a property is not defined for a particular image, this 
  85.      * method returns the <code>UndefinedProperty</code> object. 
  86.      * <p>
  87.      * If the properties for this image are not yet known, this method 
  88.      * returns <code>null</code>, and the <code>ImageObserver</code> 
  89.      * object is notified later. 
  90.      * <p>
  91.      * The property name <code>"comment"</code> should be used to store 
  92.      * an optional comment which can be presented to the application as a 
  93.      * description of the image, its source, or its author. 
  94.      * @param       name   a property name.
  95.      * @param       observer   an object waiting for this image to be loaded.
  96.      * @return      the value of the named property.
  97.      * @see         java.awt.image.ImageObserver
  98.      * @see         java.awt.Image#UndefinedProperty
  99.      * @since       JDK1.0
  100.      */
  101.     public abstract Object getProperty(String name, ImageObserver observer);
  102.  
  103.     /**
  104.      * The <code>UndefinedProperty</code> object should be returned whenever a
  105.      * property which was not defined for a particular image is fetched.
  106.      * @since    JDK1.0
  107.      */
  108.     public static final Object UndefinedProperty = new Object();
  109.  
  110.     /**
  111.      * Creates a scaled version of this image.
  112.      * A new <code>Image</code> object is returned which will render 
  113.      * the image at the specified <code>width</code> and 
  114.      * <code>height</code> by default.  The new <code>Image</code> object
  115.      * may be loaded asynchronously even if the original source image
  116.      * has already been loaded completely.  If either the <code>width</code> 
  117.      * or <code>height</code> is a negative number then a value is 
  118.      * substituted to maintain the aspect ratio of the original image 
  119.      * dimensions.
  120.      * @param width the width to which to scale the image.
  121.      * @param height the height to which to scale the image.
  122.      * @param hints flags to indicate the type of algorithm to use
  123.      * for image resampling.
  124.      * @return     a scaled version of the image.
  125.      * @see        java.awt.Image#SCALE_DEFAULT
  126.      * @see        java.awt.Image#SCALE_FAST 
  127.      * @see        java.awt.Image#SCALE_SMOOTH
  128.      * @see        java.awt.Image#SCALE_REPLICATE
  129.      * @see        java.awt.Image#SCALE_AVERAGE 
  130.      * @since      JDK1.1
  131.      */
  132.     public Image getScaledInstance(int width, int height, int hints) {
  133.     ImageFilter filter;
  134.     if ((hints & (SCALE_SMOOTH | SCALE_AREA_AVERAGING)) != 0) {
  135.         filter = new AreaAveragingScaleFilter(width, height);
  136.     } else {
  137.         filter = new ReplicateScaleFilter(width, height);
  138.     }
  139.     ImageProducer prod;
  140.     prod = new FilteredImageSource(getSource(), filter);
  141.     return Toolkit.getDefaultToolkit().createImage(prod);
  142.     }
  143.  
  144.     /**
  145.      * Use the default image-scaling algorithm.
  146.      * @since JDK1.1
  147.      */
  148.     public static final int SCALE_DEFAULT = 1;
  149.  
  150.     /**
  151.      * Choose an image-scaling algorithm that gives higher priority
  152.      * to scaling speed than smoothness of the scaled image.
  153.      * @since JDK1.1
  154.      */
  155.     public static final int SCALE_FAST = 2;
  156.  
  157.     /**
  158.      * Choose an image-scaling algorithm that gives higher priority
  159.      * to image smoothness than scaling speed.
  160.      * @since JDK1.1
  161.      */
  162.     public static final int SCALE_SMOOTH = 4;
  163.  
  164.     /**
  165.      * Use the image scaling algorithm embodied in the 
  166.      * <code>ReplicateScaleFilter</code> class.  
  167.      * The <code>Image</code> object is free to substitute a different filter 
  168.      * that performs the same algorithm yet integrates more efficiently
  169.      * into the imaging infrastructure supplied by the toolkit.
  170.      * @see        java.awt.image.ReplicateScaleFilter
  171.      * @since      JDK1.1
  172.      */
  173.     public static final int SCALE_REPLICATE = 8;
  174.  
  175.     /**
  176.      * Use the Area Averaging image scaling algorithm.  The
  177.      * image object is free to substitute a different filter that
  178.      * performs the same algorithm yet integrates more efficiently
  179.      * into the image infrastructure supplied by the toolkit.
  180.      * @see java.awt.image.AreaAveragingScaleFilter
  181.      * @since JDK1.1
  182.      */
  183.     public static final int SCALE_AREA_AVERAGING = 16;
  184.  
  185.     /**
  186.      * Flushes all resources being used by this Image object.  This
  187.      * includes any pixel data that is being cached for rendering to
  188.      * the screen as well as any system resources that are being used
  189.      * to store data or pixels for the image.  The image is reset to
  190.      * a state similar to when it was first created so that if it is
  191.      * again rendered, the image data will have to be recreated or
  192.      * fetched again from its source.
  193.      * @since JDK1.0
  194.      */
  195.     public abstract void flush();
  196. }
  197.